\chapter{QMultiMap}

template <typename Key, typename T> class QMultiMap

QMultiMap 类是一个便利的 QMap 派生类，提供多值映射功能。更多内容...

\begin{tabular}{|r|l|}
	\hline
	属性 & 方法 \\
	\hline
    头文件  &	\hl{\#include <QMultiMap>} \\
    \hline
    qmake: & QT += core    \\
    \hline
    基类: & QMap    \\
	\hline
\end{tabular}

\begin{compactitem}
\item 所有成员列表，包括继承的成员
\end{compactitem}

\begin{notice}
该类中的所有函数都是可重入的。
\end{notice}


\section{公共成员函数}


\begin{longtable}[l]{|r|m{28em}|}   
    \hline
    返回类型 	& 函数 \\
    \hline
    &QMultiMap(const QMap<Key, T> \emph{\&other}) \\
    \hline 
	&QMultiMap(std::initializer\_list<std::pair<Key, T>> \emph{list})\\
    \hline
	&QMultiMap() \\
    \hline
typename QMap<Key, T>::const\_iterator &	constFind(const Key \emph{\&key}, const T \emph{\&value}) const \\
\hline
bool 	& contains(const Key \&key, const T \emph{\&value}) const\\
\hline
int 	& count(const Key \&key, const T \emph{\&value}) const\\
\hline
typename QMap<Key, T>::iterator 	& find(const Key \emph{\&key}, const T \emph{\&value})\\
\hline
typename QMap<Key, T>::const\_iterator &	find(const Key \emph{\&key}, const T \emph{\&value}) const\\
\hline
typename QMap<Key, T>::iterator &insert(const Key \emph{\&key}, const T \emph{\&value})\\
\hline
typename QMap<Key, T>::iterator & insert(typename QMap<Key, T>::const\_iterator \emph{pos}, const Key \emph{\&key}, const T \emph{\&value}) \\
\hline
int &	remove(const Key \emph{\&key}, const T \emph{\&value}) \\
\hline
typename QMap<Key, T>::iterator &	replace(const Key \emph{\&key}, const T \emph{\&value}) \\
\hline
void 	&swap(QMultiMap<Key, T> \emph{\&other})\\
\hline
QList &	uniqueKeys() const \\
\hline
QMultiMap<K, V> \& &	unite(const QMultiMap<K, V> \emph{\&other}) \\
\hline
QList &	values(const Key \emph{\&key}) const \\
\hline
QMultiMap<K, V> 	&operator+(const QMultiMap<K, V> \emph{\&other}) const \\
\hline
QMultiMap<K, V> \& &	operator+=(const QMultiMap<K, V> \emph{\&other}) \\
    \hline
\end{longtable}


\section{详细描述}

QMultiMap<Key, T> 是一种 Qt 泛型容器类。
它继承 QMap 并扩展了一些功能，使之可以存储多值映射。
多值映射是一种允许将多个值关联到同一个键的映射；
QMap 不允许多值映射。

因为 QMultiMap 继承 QMap，所有 QMap 的功能也适用于 QMultiMap。
例如，可以使用 isEmpty() 测试 map 是否为空，可以使用 QMap 的迭代器类（例如 QMapIterator）遍历 QMultiMap。
除此之外，它还提供 insert() 函数来插入值，如果要插入的键已经存在，该函数不会覆盖已有的值，而 replace() 函数则不同，
如果 map 中已经存在要插入的键，该函数会覆盖已经存在的值。
此外，该类还提供方便的 operator+() 和 operator+=() 运算符。

例子：

\begin{cppcode}
QMultiMap<QString, int> map1, map2, map3;

map1.insert("plenty", 100);
map1.insert("plenty", 2000);
// map1.size() == 2

map2.insert("plenty", 5000);
// map2.size() == 1

map3 = map1 + map2;
// map3.size() == 3
\end{cppcode}

%%%%%%%

与 QMap 不同，QMultiMap 不提供 operator[] 运算符。
如果想用特定键访问最新插入的元素，使用 value() 或 replace()。

如果想取得单个键关联的所有值，可以使用 values(const Key \&key)，
该函数返回一个 QList：

\begin{cppcode}
QList<int> values = map.values("plenty");
for (int i = 0; i < values.size(); ++i)
    cout << values.at(i) << Qt::endl;
\end{cppcode}

共享同一键的元素按照从最新到最早插入的顺序返回。

如果习惯用 STL 风格迭代器，可以传递键调用 find() 取得第一个元素的迭代器，从该元素开始遍历：

\begin{cppcode}
QMultiMap<QString, int>::iterator i = map.find("plenty");
while (i != map.end() && i.key() == "plenty") {
    cout << i.value() << Qt::endl;
    ++i;
}
\end{cppcode}

QMultiMap 键和值的数据类型必须是可赋值数据类型。
这涵盖了大多数可能会遇到的数据类型，但是编译器不会允许存储类似 QWidget 这样的对象作为值，
应该存储 QWidget *。另外，QMultiMap 的键类型必须提供 operator<() 运算符。 
具体请参考 QMap 文档。

\begin{seeAlso}
QMap，QMapIterator，QMutableMapIterator 和 QMultiHash。
\end{seeAlso}

\section{成员函数文档}

QMultiMap::QMultiMap(const QMap<Key, T> \emph{\&other})

构造一个 other 的副本（可能是一个 QMap 或 QMultiMap）。

\begin{seeAlso}
operator=()。
\end{seeAlso}

QMultiMap::QMultiMap(std::initializer\_list<std::pair<Key, T>> \emph{list})

用初始化列表 list 中每个元素的副本构造一个 multi-map。

只有当程序在 C++11 模式下编译时，该函数才可用。

Qt 5.1 中引入该函数。

QMultiMap::QMultiMap()

构造一个空 map。

typename QMap<Key, T>::const\_iterator QMultiMap::constFind(const Key \emph{\&key}, const T \emph{\&value}) const

返回迭代器，指向 map 中键为 key，值为 value 的元素。

如果 map 中不包含这样的元素，该函数返回 constEnd()。

Qt 4.3 中引入该函数。

\begin{seeAlso}
QMap::constFind()。
\end{seeAlso}

bool QMultiMap::contains(const Key \emph{\&key}, const T \emph{\&value}) const

如果该 map 包含键为 key，值为 value 的元素，返回 true；否则返回 false。

Qt 4.3 中引入该函数。

\begin{seeAlso}
QMap::contains()。
\end{seeAlso}

int QMultiMap::count(const Key \emph{\&key}, const T  \emph{\&value}) const

返回键为 key，值为 value 的元素个数。

Qt 4.3 中引入该函数。

\begin{seeAlso}
QMap::count()。
\end{seeAlso}

typename QMap<Key, T>::iterator QMultiMap::find(const Key \emph{\&key}, const T \emph{\&value})

返回迭代器，指向 map 中键为 key，值为 value 的元素。

如果 map 中不包含这样的元素，该函数返回 end()。

如果 map 包含多个键为 key （译者注：以及值为 value）的元素，函数返回指向最新插入的那个值的迭代器。

Qt 4.3 中引入该函数。

\begin{seeAlso}
QMap::find()。
\end{seeAlso}

typename QMap<Key, T>::const\_iterator QMultiMap::find(const Key \emph{\&key}, const T \emph{\&value}) const

这是一个重载函数。

返回常量迭代器，指向 map 中键为 key，值为 value 的元素。

如果 map 中不包含这样的元素，该函数返回 end()。

如果 map 包含多个键为 key（译者注：以及值为 value）的元素，函数返回指向最新插入的那个值的常量迭代器。

Qt 4.3 中引入该函数。

\begin{seeAlso}
QMap::find()。
\end{seeAlso}

typename QMap<Key, T>::iterator QMultiMap::insert(const Key \emph{\&key}, const T \emph{\&value})

用键 key 和值 value 插入一个新元素。

如果 map 中已经存在相同键的元素，该函数将创建一个新元素。
（这与 replace() 不同，replace() 是覆盖已经存在元素的值。)

\begin{seeAlso}
replace()。
\end{seeAlso}

typename QMap<Key, T>::iterator QMultiMap::insert(typename QMap<Key, T>::const\_iterator \emph{pos}, const Key \emph{\&key}, const T \emph{\&value})

用键 key 和值 value 插入一个新元素，pos 用来提示插入位置。

如果以 constBegin() 作为插入位置提示，表明 key 比 map 中的任何键都小，
而 constEnd() 则建议 key 大于 map 中的任何键。
否则提示应该满足条件 (pos - 1).key() < key <= pos.key()。
如果提示 pos 是错误的，其将被忽略，并以常规方式插入。

如果 map 中已经存在相同键的元素，该函数将创建一个新元素。

\begin{notice}
需小心对待提示。提供从旧的共享实例取得的迭代器可能引起崩溃，还会有默默污染 map 和 pos 的 map 的风险。
\end{notice}

Qt 5.1 中引入该函数。

int QMultiMap::remove(const Key \emph{\&key}, const T \emph{\&value})

从 map 中移除所有键为 key，值为 value 的元素。返回被移除元素的个数。

Qt 4.3 中引入该函数。

\begin{seeAlso}
QMap::remove()。
\end{seeAlso}

typename QMap<Key, T>::iterator QMultiMap::replace(const Key \emph{\&key}, const T \emph{\&value})

用键 key 和值 value 插入一个新元素。

如果已经存在键为 key 的元素，该元素的值将被 value 替换。

如果有多个键为 key 的元素，最新插入的元素的值将被 value 替换。

\begin{seeAlso}
insert()。
\end{seeAlso}

void QMultiMap::swap(QMultiMap<Key, T> \&other)

将 map other 与本 map 交换。该操作非常快，永远不失败。

Qt 4.8 中引入该函数。
QList QMultiMap::uniqueKeys() const

以升序返回 map 中所有键的列表。在 map 中多次出现的键在返回的列表中只出现一次。

Qt 4.2 中引入该函数。

QMultiMap<K, V> \&QMultiMap::unite(const QMultiMap<K, V> \emph{\&other})

将 other map 中的所有元素插入到本 map 中。
如果一个键在两个 map 中同时存在，结果 map 将多次包含这个键。

\lineHigh

QList QMultiMap::values(const Key \emph{\&key}) const

按照从最新到最早插入的顺序，返回所有与键 \emph{key} 相关联的值的列表。

\lineHigh

QMultiMap<K, V> QMultiMap::operator+(const QMultiMap<K, V> \emph{\&other}) const

返回一个 map，该 map 包含本 map 和 \emph{other} map 中的所有元素。
如果一个键在两个 map 中同时存在，结果 map 将多次包含这个键。

\begin{seeAlso}
operator+=()。
\end{seeAlso}

\lineHigh

QMultiMap<K, V> \&QMultiMap::operator+=(const QMultiMap<K, V> \emph{\&other})

将 \emph{other} map 中的所有元素插入到本 map 中，返回本 map 的引用。

\begin{seeAlso}
insert() 和 operator+()。
\end{seeAlso}